\section{User Manual}
\subsection{Installation and running the examples}
\subsubsection{Installation}
\texttt{cl-ass} does not require any installation. To use the library, you just need to load the included files \texttt{cl-ass.lisp} and (optionally) \texttt{capi-loader.lisp} (in any order; however, if you load capi first, you need to have the Lisp path set up to the same directory where cl-ass is\footnote{\texttt{(hcl:change-directory }\textit{path}\texttt{)}}).

\texttt{cl-ass} can, optionally, use \texttt{cl:store} for serializing the framework. If you want to use \texttt{cl:store}, you need to have \texttt{quicklisp}\footnote{http://www.quicklisp.org/beta/} ready and loaded before loading \texttt{cl-ass}. You may opt out of this dependency by not having quicklisp; however, you will not be able to store the current state of the simulation during the export.
\subsubsection{Loading examples}
Every example requires the Lisp path to be set to the directory where the example file is located, and that directory must be inside the directory where cl-ass (and optionally, capi-loader) reside to correctly auto-load the dependencies.

Three examples are provided with the \texttt{cl-ass} framework:
\begin{itemize}
	\item \texttt{example-cli.lisp} - Simple reflexive agent, simulating an automated vacuum cleaner, with no GUI
	\item \texttt{example-ma-cli.lisp} - Swarm intelligence, with automatic closest path searching ant-agents
	\item \texttt{example-gui.lisp} - Same simulation as in \texttt{example-cli.lisp}, with a GUI
\end{itemize}
\subsection{How to use}
In this section, a concrete agent simulation based on Simple Reflex Agents\cite{russelnorvig} is presented as an example of how to use the cl-ass framework.
\subsubsection{Environment}
Every simulation must contain a defined environment. In our example, the environment is a simple, flat, 2-dimensional land with randomly-generated clean or dirty tiles. We define the environment via the \texttt{defenvironment} macro \pref{defenvironment}. Our dirty flatland only contains the world (2D array) and the current position of our agent as its slots.
\begin{example}[caption=Defining new environment]
(defenvironment dirty-flatland 
                ((current-agent-position :initform 0 :accessor agent-position)
                 (flatland :initform nil :accessor flatland)))
\end{example}

We need to provide a method for this environment that will take care of initializing every new instance of it.

\begin{example}[caption=Method for initializing new environment]
(defmethod initialize-environment ((e dirty-flatland) s)
  (let* ((len (+ 5 (random 4)))
        (pos (random len)))
    (let ((vec (make-array len)))
      (dotimes (i len)
        (setf (aref vec i)
              (if (= (random 2) 0)
                  :dirty
                :clean)))
      (setf (agent-position e) pos)
      (setf (flatland e) vec))))
\end{example}

We should also provide methods for our agent to later use to modify the environment. \texttt{agent-tile} is used to return where our agent is standing in our 2D world. \texttt{clean-agent-tile} will clean the current tile where our agent is standing, and methods \texttt{left} and \texttt{right} will move the agent left or right (or not at all, if it is at the edge of our 2D world).

\begin{example}[caption=Methods for modifying environment]
(defmethod agent-tile ((e dirty-flatland))
  (aref (flatland e) (agent-position e)))

(defmethod clean-agent-tile ((e dirty-flatland))
  (setf (aref (flatland e) (agent-position e))
        :clean))

(defmethod left ((e dirty-flatland))
  (setf (agent-position e) 
        (max 0
             (1- (agent-position e)))))

(defmethod right ((e dirty-flatland))
  (setf (agent-position e)
        (min (1- (length (flatland e)))
             (1+ (agent-position e)))))
\end{example}

\subsubsection{Agent}
Next, we need to define our agent classes. In our example, we have a single agent simulation, so we only need to define one agent class, namely \textbf{vacuum-cleaner}. We use the macro \texttt{defagent}\pref{defagent} to define our agent. Our agent will only have one defined slot, \texttt{cleaned-tiles}, where we will count the number of tiles that agent has cleaned so far.

\begin{example}[caption=Defining our agent]
(defagent vacuum-cleaner ((cleaned-tiles :initform 0 :accessor cleaned-tiles)))
\end{example}

Our agent needs to be able to query the environment. For that, we need to define a set of percepts. But since our agent is very simple, we only need one percept, namely \texttt{is-dirty?}, which queries whether the current tile is dirty. We can define our percept via the \texttt{defpercept} macro \pref{defpercept}.

\begin{example}[caption=is-dirty? percept definition]
(defpercept is-dirty? ((agent vacuum-cleaner) e)
  (eq (agent-tile e) :dirty))
\end{example}

In order for our agent to modify the environment, it needs a set of actuators. We define four actuators via the \texttt{defactuator} macro\pref{defactuator}. 
\texttt{suck}, which cleans the current tile, \texttt{go-left} and \texttt{go-right} which move the agent in the environment, and \texttt{contemplate}, which makes our agent do nothing this iteration.

\begin{example}[caption=Defining actuators]
(defactuator suck ((agent vacuum-cleaner) e)
  (clean-agent-tile e))

(defactuator go-left ((agent vacuum-cleaner) e)
  (left e))

(defactuator go-right ((agent vacuum-cleaner) e)
  (right e))

(defactuator contemplate ((agent vacuum-cleaner) e)
  )
\end{example}

The final thing we need to define for our agent is its \texttt{agent-function} method\pref{agentfunction}. This function will be the main logic hub of the agent. We need to return lists of actuators out of every branch of our agent function.

\begin{example}[caption=Simple Vacuum Cleaner agent function]
(defmethod agent-function ((agent vacuum-cleaner))
  (with-slots (is-dirty?) agent
    (cond (is-dirty? (incf (cleaned-tiles agent))
                     (list 'suck))
          (t (let ((a (random 3)))
               (cond ((= a 0) (list 'contemplate))
                     ((= a 1) (list 'go-left))
                     (t (list 'go-right))))))))
\end{example}

\subsubsection{Simulation}
At the end, we define our simulation via the \texttt{defsimulation} macro\pref{defsimulation}. We provide a name, an empty list of slots, a name for our environment class, and a list of agent classes - in our case, only a single \texttt{vacuum-cleaner} agent.

\begin{example}[caption=Defining simulation]
(defsimulation vacuum-cleaner-simulation () 
                          dirty-flatland (vacuum-cleaner))
\end{example}

We may now use our simulation to simulate our agent in our environment. For that, we need to make an instance of our simulation, initialize it via \texttt{initialize-simulation}\pref{initializesimulation} and then iterate over simulation steps via the \texttt{iterate} method\pref{iterate}.

\begin{example}[caption=Running the simulation]
> (setf *simulation* (make-instance 'vacuum-cleaner-simulation))
#<VACUUM-CLEANER-SIMULATION 20093A1B>

> (initialize-simulation *simulation*)
#<VACUUM-CLEANER-SIMULATION 20093A1B>

> (iterate *simulation*)
NIL

> (iterate *simulation* 1000)
NIL
\end{example}

We can also query information about our simulation. 

\begin{example}[caption=Querying the simulation]
> (agents *simulation*)
(#<VACUUM-CLEANER 2198BD2B>)

> (cleaned-tiles (first (agents *simulation*)))
4

> (agent-position (environment *simulation*))
1

> (flatland (environment *simulation*))
#(:CLEAN :DIRTY :DIRTY :CLEAN :DIRTY :CLEAN :CLEAN)
\end{example}

\subsubsection{Complete example}
%complete example
Here is the complete source code to the vacuum cleaning agent presented in previous sections.

\begin{example}[caption=Random vacuum cleaning agent simulation]
(defenvironment dirty-flatland 
                ((current-agent-position :initform 0 :accessor agent-position)
                 (flatland :initform nil :accessor flatland)))

(defmethod initialize-environment ((e dirty-flatland) s)
  (let* ((len (random 1000))
        (pos (random len)))
    (let ((vec (make-array len)))
      (dotimes (i len)
        (setf (aref vec i)
              (if (= (random 2) 0)
                  :dirty
                :clean)))
      (setf (agent-position e) pos)
      (setf (flatland e) vec))))

(defmethod agent-tile ((e dirty-flatland))
  (aref (flatland e) (agent-position e)))

(defmethod clean-agent-tile ((e dirty-flatland))
  (setf (aref (flatland e) (agent-position e))
        :clean))

(defmethod left ((e dirty-flatland))
  (setf (agent-position e) 
        (max 0
             (1- (agent-position e)))))

(defmethod right ((e dirty-flatland))
  (setf (agent-position e)
        (min (1- (length (flatland e)))
             (1+ (agent-position e)))))

(defagent vacuum-cleaner ((cleaned-tiles :initform 0 :accessor cleaned-tiles)))

(defpercept is-dirty? ((agent vacuum-cleaner) e)
  (eq (agent-tile e) :dirty))

(defactuator suck ((agent vacuum-cleaner) e)
  (clean-agent-tile e))

(defactuator go-left ((agent vacuum-cleaner) e)
  (left e))

(defactuator go-right ((agent vacuum-cleaner) e)
  (right e))

(defactuator contemplate ((agent vacuum-cleaner) e)
  )

(defmethod agent-function ((agent vacuum-cleaner))
  (with-slots (is-dirty?) agent
    (cond (is-dirty? (incf (cleaned-tiles agent))
                     (list 'suck))
          (t (let ((a (random 3)))
               (cond ((= a 0) (list 'contemplate))
                     ((= a 1) (list 'go-left))
                     (t (list 'go-right))))))))

(defsimulation vacuum-cleaner-simulation () 
                          dirty-flatland (vacuum-cleaner))

\end{example}

\subsection{Full API Documentation}
\subsubsection{Environment}
\label{environmentclass}
\textit{Class} \textbf{ENVIRONMENT-CLASS} \\
\\
\textbf{Class Precedence List:} \\
\\
\textbf{storable-class}\pref{storableclass} \textbf{standard-class} \textbf{t}
\\ \\
\label{environment}
\textit{Class} \textbf{ENVIRONMENT} \\
\\
\textbf{Class Precedence List:} \\
\\
\textbf{environment-class} \textbf{storable-class}\pref{storableclass} \textbf{standard-class} \textbf{t}
\\ \\ 

\label{defenvironment}
\textit{Macro} \textbf{DEFENVIRONMENT} \\
\textbf{Syntax:} \\
\textbf{defenvironment} \textit{name (\{slot-specifier\}*)} \\
$ \Rightarrow $ \textit{new-class} 
\begin{verbatim}
slot-specifier::= slot-name | (slot-name [[slot-option]])
slot-name::= symbol
slot-option::= {:reader reader-function-name}* | 
               {:writer writer-function-name}* | 
               {:accessor reader-function-name}* | 
               {:initform form} | 
               {:type type-specifier} | 
               {:documentation string} 
function-name::= {symbol | (setf symbol)}
\end{verbatim}
\textbf{Arguments and Values:} \\
\textit{name} a non-nil symbol \\
\textit{slot-name} a symbol that is syntactically valid for use as a variable name \\
\textit{reader-function-name} a non-nil symbol \\
\textit{writer-function-name} a generic function name \\
\textit{form} form \\
\textit{type-specifier} a type specifier \\ \\
Macro \textbf{defenvironment} defines a new environment and returns it as a new class. This new class will have \texttt{environment}\pref{environment} as its superclass.
\begin{snippet}
(defenvironment house 
   ((rooms :initform (generate-rooms) :accessor rooms)))
\end{snippet} 

\label{initializeenvironment}
\textit{Generic Function} \textbf{initialize-environment} \\
\textbf{Syntax:} \\
\textbf{initialize-environment} \textit{environment simulation} \\
$ \Rightarrow $ \textit{undefined} \\ \\
\texttt{Initialize-environment} is a method that is called every time a simulation is initialized and should prepare the underlying environment for its execution. Every environment must have at least one \texttt{initialize-environment} method defined.
\begin{snippet}
(defmethod initialize-environment ((env house) simulation)
    ... )
\end{snippet}

\subsubsection{Agent}
\label{agentclass}
\textit{Class} \textbf{AGENT-CLASS} \\
\\
\textbf{Class Precedence List:} \\
\\
\textbf{storable-class}\pref{storableclass} \textbf{standard-class} \textbf{t}
\\ \\
\label{agent}
\textit{Class} \textbf{AGENT} \\
\\
\textbf{Class Precedence List:} \\
\\
\textbf{agent-class} \textbf{storable-class}\pref{storableclass} \textbf{standard-class} \textbf{t}
\\ \\ 

\label{defagent}
\textit{Macro} \textbf{DEFAGENT} \\
\textbf{Syntax:} \\
\textbf{defagent} \textit{name (\{slot-specifier\}*)} \\
$ \Rightarrow $ \textit{new-class} 
\begin{verbatim}
slot-specifier::= slot-name | (slot-name [[slot-option]])
slot-name::= symbol
slot-option::= {:reader reader-function-name}* | 
               {:writer writer-function-name}* | 
               {:accessor reader-function-name}* | 
               {:initform form} | 
               {:type type-specifier} | 
               {:documentation string} 
function-name::= {symbol | (setf symbol)}
\end{verbatim}
\textbf{Arguments and Values:} \\
\textit{name} a non-nil symbol \\
\textit{slot-name} a symbol that is syntactically valid for use as a variable name \\
\textit{reader-function-name} a non-nil symbol \\
\textit{writer-function-name} a generic function name \\
\textit{form} form \\
\textit{type-specifier} a type specifier \\ \\
Macro \textbf{defagent} defines a new agent and returns it as a new class. This new class will have \texttt{agent}\pref{agent} as its superclass.
\begin{snippet}
(defagent mouse 
  ((stomach :initform :empty :accessor stomach)
   (bravery :initform 0 :accessor bravery)
   (alive :initform t :accessor alive-p)))
\end{snippet}

\label{defpercept}
\textit{Macro} \textbf{DEFPERCEPT} \\
\textbf{Syntax:} \\
\textbf{defpercept} \textit{name ((variable agent-type) environment) form*} \\
$ \Rightarrow $ \textit{new-method} \\ \\
\textbf{Arguments and Values:} 
\textit{name} a symbol that is syntactically valid for use as a method name \\
\textit{variable} a symbol that is syntactically valid for use as a variable \\
\textit{agent-type} type \\
\textit{environment} a symbol that is syntactically valid for use as a variable \\
\textit{form} form \\ \\
Macro \textbf{defpercept} defines a new percept for an agent. A percept is a method bound for the type specified by agent-type. The body of the method defined by \textbf{defpercept} must return some value which should be obtained from the environment.
Additionally, every percept defined for the agent adds a new slot to the agent class with the same name as the name argument. This can be used later, in \texttt{agent-function} to query the percept value.
\begin{snippet}
(defpercept near-cheese? ((agent mouse) env)
   (has-items (get-room-of env agent) :cheese))
\end{snippet}

\label{defactuator}
\textit{Macro} \textbf{DEFACTUATOR} \\
\textbf{Syntax:} \\
\textbf{defactuator} \textit{name ((variable agent-type) environment) form*} \\
$ \Rightarrow $ \textit{new-method} \\ \\
\textbf{Arguments and Values:} 
\textit{name} a symbol that is syntactically valid for use as a method name \\
\textit{variable} a symbol that is syntactically valid for use as a variable \\
\textit{agent-type} type \\
\textit{environment} a symbol that is syntactically valid for use as a variable \\
\textit{form} form \\ \\
Macro \textbf{defactuator} defines a new actuator for an agent. The actuator is a method bound for the type specified by agent-type. The body of the method defined by \textbf{defactuator} can modify the environment and represents actions that the agent wants to take.
\begin{snippet}
(defpercept eat-cheese ((agent mouse) env)
   (remove-item (get-room-of env agent) :cheese))
\end{snippet}

\label{agentfunction}
\textit{Generic Function} \textbf{AGENT-FUNCTION} \\
\textbf{Syntax:} \\
\textbf{agent-function} \textit{agent} \\
$ \Rightarrow $ \textit{list of actuators} \\ \\
\textbf{Arguments and Values:} \\
\textit{list of actuators} nil or a list containing symbols which are defined as actuators for this agent \\
\texttt{agent-function} is the main method of an agent. In this method, the agent should query slots with the same names as the percepts defined for that agent and decide which actions to take. Actions are then returned as a list of actuators.
\begin{snippet}
(defmethod agent-function ((agent mouse))
  (with-slots (near-cheese? north? south? east? west? cat-in-room?) agent
     (cond (((and near-cheese? (not cat-in-room?))
                 '(eat-cheese))
                (cat-in-room?
                  (...
      ...)
\end{snippet}

\subsubsection{Simulation}

\label{simulationclass}
\textit{Class} \textbf{SIMULATION-CLASS} \\
\\
\textbf{Class Precedence List:} \\
\\
\textbf{storable-class}\pref{storableclass} \textbf{standard-class} \textbf{t}
\\ \\

\label{simulation}
\textit{Class} \textbf{SIMULATION} \\
\\
\textbf{Class Precedence List:} \\
\\
\textbf{simulation-class} \textbf{storable-class}\pref{storableclass} \textbf{standard-class} \textbf{t}
\\
\textbf{Slots:} \\
\\
\textit{environment}, \textbf{accessor}: \textit{environment} - an instance of the current environment \\
\textit{agents}, \textbf{accessor}: \textit{agents} - the list of all currently instantiated agents
\\ \\ \\

\label{defsimulation}
\textit{Macro} \textbf{DEFSIMULATION} \\
\textbf{Syntax:} \\
\textbf{defsimulation} \textit{name (\{slot-specifier\}*) environment-class (\{agent\}*) } \\
$ \Rightarrow $ \textit{new-class} 
\begin{verbatim}
slot-specifier::= slot-name | (slot-name [[slot-option]])
slot-name::= symbol
slot-option::= {:reader reader-function-name}* | 
               {:writer writer-function-name}* | 
               {:accessor reader-function-name}* | 
               {:initform form} | 
               {:type type-specifier} | 
               {:documentation string} 
function-name::= {symbol | (setf symbol)}
\end{verbatim}
\textbf{Arguments and Values:} \\
\textit{name} a non-nil symbol \\
\textit{slot-name} a symbol that is syntactically valid for use as a variable name \\
\textit{reader-function-name} a non-nil symbol \\
\textit{writer-function-name} a generic function name \\
\textit{form} form \\
\textit{type-specifier} a type specifier \\ 
\textit{environment-class} a type specifier \\ 
\textit{agent} a type specifier \\ 
Macro \textbf{defsimulation} defines a new simulation and returns it as a new class. Every simulation defined by defsimulation will have \texttt{simulation}\pref{simulation} as its superclass.
\begin{snippet}
(defsimulation cat-and-mouse 
  ((iteration-count :initform 0 :accessor it-count))
  house
  (mouse mouse mouse cat cat))
\end{snippet}

\label{initializesimulation}
\textit{Generic Function} \textbf{INITIALIZE-SIMULATION} \\
\textbf{Syntax:} \\
\textbf{initialize-simulation} \textit{simulation} \\
$ \Rightarrow $ \textit{simulation} \\ \\
\textbf{Method signatures:} \\
\textbf{initialize-simulation} \textit{(s simulation)} \\
\textbf{Arguments and Values:} \\
\textit{simulation} a simulation instance \\ \\
Method initialize-simulation should be called when you want to reset the simulation to a pristine state. A new environment and agents are instantiated and generated.
\begin{snippet}
> (initialize-simulation *simulation*)
#<CAT-AND-MOUSE 200E59F7>
\end{snippet}

\label{iterate}
\textit{Generic Function} \textbf{ITERATE} \\
\textbf{Syntax:} \\
\textbf{iterate} \textit{simulation} \&optional \textit{(n 1)} \\
$ \Rightarrow $ \textit{NIL} \\ \\
\textbf{Method signatures:} \\
\textbf{iterate} \textit{(s simulation)} \\
\textbf{Arguments and Values:} \\
\textit{simulation} a simulation instance \\
\textit{n} an integer \\ \\
Iterates the simulation n times.
\begin{snippet}
> (iterate *simulation*)
NIL
\end{snippet}
\subsubsection{Export}

\label{storableclass}
\textit{Class} \textbf{STORABLE-CLASS} \\
\\
\textbf{Class Precedence List:} \\
\\
\textbf{standard-class} \textbf{t}
\\
\textbf{Slots:} \\
\\
\textit{import-file}, \textbf{accessor}: \textit{import-file} - list of strings \\ \\
Every class that you want to be able to export should have \texttt{storable-class} as one of its superclasses. In the import-file, you can store additional source dependencies which will be copied into the exported file.
\\ \\ \\

\label{exportsimulation}
\textit{Function} \textbf{EXPORT-SIMULATION} \\
\textbf{Syntax:} \\
\textbf{export-simulation} \textit{export-file} \&key \textit{simulation-instance (path ".")} $ \Rightarrow $ \textit{NIL} \\ \\
\textbf{Arguments and Values:} \\
\textit{export-file} a string with the file name to which you want to export the simulation (will be overwritten) \\ 
\textit{simulation-instance} a simulation instance. If provided, it will be stored in the \texttt{deserialize-saved-state} function at the end of file \\
\textit{path} a string. It is combined with import-file dependencies of all storable-classes \\ \\
This functions takes all \texttt{storable-class}es defined in the current Lisp environment and defines which files these classes require by querying import-file. It then combines all these files into a single output file specified by the export-file argument. Then it exports all class definitions which have \texttt{storable-class} as their class 
precedence list along with all their methods, provided they are evaluated and not compiled. If the simulation-instance argument is provided, it is stored via cl:store into a specific function \texttt{deserialize-saved-state}.
\\ \\ 

\label{deserializesavedstate}
\textit{Function} \textbf{DESERIALIZE-SAVED-STATE} \\
\textbf{Syntax:} \\
\textbf{export-simulation} $ \Rightarrow $ \textit{simulation-instance} \\ \\
\textbf{Arguments and Values:} \\
\textit{simulation-instance} a simulation instance \\ \\
This functions returns an instance of a previously-exported simulation. This function is read-only and will always return a new instance with the same state that it had at the time of export.

\begin{snippet}
> (deserialize-saved-state)
#<CAT-AND-MOUSE 200E80DE>
\end{snippet}

\subsection{Graphics library}
Included with cl-ass is a small library based on CAPI \footnote{CAPI is a multiplatform GUI toolkit included with LispWorks. See more at http://www.lispworks.com/products/capi.html} included in LispWorks. The library is included in \texttt{capi-loader.lisp}.
\subsubsection{How to use}
Building off of the previous example, we only need to make minor changes to include graphics. Firstly, we need to define our simulation with \texttt{defgsimulation}\pref{defgsimulation} instead of \texttt{defsimulation}\pref{defsimulation}.

\begin{example}[caption=Defining graphics simulation]
(defgsimulation vacuum-cleaner-simulation ((graphics :accessor graphics :initform nil)) dirty-flatland (vacuum-cleaner) ())
\end{example}

We need to define the \texttt{clear-pane}\pref{clearpane} method. In it, during the first render call, we can load and convert images for the output pane. 

\begin{example}[caption=Defining clean-pane for our simulation]
(defmethod clear-pane ((s vacuum-cleaner-simulation) pane)
 (unless (graphics s)
    (let ((r (render-panel s)))
      (setf (graphics s)
            (list (cons :clean   (gp:convert-external-image r (gp:read-external-image "images/empty.png")))
                  (cons :dirty   (gp:convert-external-image r (gp:read-external-image "images/dirty.png")))
                  (cons :c-agent (gp:convert-external-image r (gp:read-external-image "images/empty_agent.png")))
                  (cons :d-agent (gp:convert-external-image r (gp:read-external-image "images/dirty_agent.png")))))))
  (gp:clear-graphics-port pane))
\end{example}

As a last thing, we need to define a way to render our simulation via the \texttt{render-pane}\pref{renderpane} method.

\begin{example}[caption=Defining rendering]
(defmethod render-pane ((s vacuum-cleaner-simulation) pane)
  (let ((e (environment s)))
    (let ((xpos 10))
      (dotimes (i (length (flatland e)))
        (let ((type (aref (flatland e) i)))
          (if (= i (agent-position e))
              (draw-agent s pane type xpos)
            (draw-empty s pane type xpos))
          (incf xpos 85))))))

(defun draw-agent (s pane type xpos)
  (draw-tile (assoc (if (eq type :dirty) :d-agent :c-agent) (graphics s)) pane xpos))

(defun draw-empty (s pane type xpos)
  (draw-tile (assoc type (graphics s)) pane xpos))

(defun draw-tile (img pane xpos)
  (gp:draw-image pane (cdr img) xpos 50))
\end{example}

We can then run the simulation by simply instantiating the defined simulation:

\begin{example}[caption=Running the simulation]
> (setf *simulation* (make-instance 'vacuum-cleaner-simulation))
#<VACUUM-CLEANER-SIMULATION 20093A1B>
\end{example}
\begin{figure}[H]
    \centering
    \includegraphics[width=0.8\textwidth,natwidth=815,natheight=661]{01.png}
    \caption{Vacuum Cleaner simulation in graphics.}
    \label{fig:vacuum_sim}
\end{figure}

\subsubsection{Complete example}
Here is the complete source code to the vacuum cleaning agent presented in the previous sections.

\begin{example}[caption=Random vacuum cleaning agent simulation - graphics version]
(defenvironment dirty-flatland 
                ((current-agent-position :initform 0 :accessor agent-position)
                 (flatland :initform nil :accessor flatland)))

(defmethod agent-tile ((e dirty-flatland))
  (aref (flatland e) (agent-position e)))

(defmethod clean-agent-tile ((e dirty-flatland))
  (setf (aref (flatland e) (agent-position e))
        :clean))

(defmethod left ((e dirty-flatland))
  (setf (agent-position e) 
        (max 0
             (1- (agent-position e)))))

(defmethod right ((e dirty-flatland))
  (setf (agent-position e)
        (min (1- (length (flatland e)))
             (1+ (agent-position e)))))

(defmethod initialize-environment ((e dirty-flatland) s)
  (let* ((len (+ 5 (random 4)))
        (pos (random len)))
    (let ((vec (make-array len)))
      (dotimes (i len)
        (setf (aref vec i)
              (if (= (random 2) 0)
                  :dirty
                :clean)))
      (setf (agent-position e) pos)
      (setf (flatland e) vec))))

(defagent vacuum-cleaner ((cleaned-tiles :initform 0 :accessor cleaned-tiles)))

(defpercept is-dirty? ((agent vacuum-cleaner) e)
  (eq (agent-tile e) :dirty))

(defactuator suck ((agent vacuum-cleaner) e)
  (clean-agent-tile e))

(defactuator go-left ((agent vacuum-cleaner) e)
  (left e))

(defactuator go-right ((agent vacuum-cleaner) e)
  (right e))

(defactuator contemplate ((agent vacuum-cleaner) e)
  )

(defmethod agent-function ((agent vacuum-cleaner))
  (with-slots (is-dirty?) agent
    (cond (is-dirty? (incf (cleaned-tiles agent))
                     (list 'suck))
          (t (let ((a (random 3)))
               (cond ((= a 0) (list 'contemplate))
                     ((= a 1) (list 'go-left))
                     (t (list 'go-right))))))))

(defgsimulation vacuum-cleaner-simulation ((graphics :accessor graphics :initform nil)) dirty-flatland (vacuum-cleaner) ())

(defmethod clear-pane ((s vacuum-cleaner-simulation) pane)
 (unless (graphics s)
    (let ((r (render-panel s)))
      (setf (graphics s)
            (list (cons :clean   (gp:convert-external-image r (gp:read-external-image "images/empty.png")))
                  (cons :dirty   (gp:convert-external-image r (gp:read-external-image "images/dirty.png")))
                  (cons :c-agent (gp:convert-external-image r (gp:read-external-image "images/empty_agent.png")))
                  (cons :d-agent (gp:convert-external-image r (gp:read-external-image "images/dirty_agent.png")))))))
  (gp:clear-graphics-port pane))

(defmethod render-pane ((s vacuum-cleaner-simulation) pane)
  (let ((e (environment s)))
    (let ((xpos 10))
      (dotimes (i (length (flatland e)))
        (let ((type (aref (flatland e) i)))
          (if (= i (agent-position e))
              (draw-agent s pane type xpos)
            (draw-empty s pane type xpos))
          (incf xpos 85))))))

(defun draw-agent (s pane type xpos)
  (draw-tile (assoc (if (eq type :dirty) :d-agent :c-agent) (graphics s)) pane xpos))

(defun draw-empty (s pane type xpos)
  (draw-tile (assoc type (graphics s)) pane xpos))

(defun draw-tile (img pane xpos)
  (gp:draw-image pane (cdr img) xpos 50))
\end{example}

\subsubsection{Graphics api}
\label{simulationinterface}
\textit{Class} \textbf{SIMULATION-INTERFACE} \\
\\
\textbf{Class Precedence List:} \\
\\
\textbf{capi:interface}
\\
\textbf{Slots:} \\
\textit{simulation}, \textbf{accessor}: \textit{simulation} - simulation instance \\ \\
Graphics simulation uses this interface subclass as the main interface. It only has a single new slot, \texttt{simulation}, which contains the bound \texttt{graphics-simulation}\pref{graphicssimulation} instance.
\\ \\ \\
\label{graphicssimulation}
\textit{Class} \textbf{GRAPHICS-SIMULATION} \\
\\
\textbf{Class Precedence List:} \\
\\
\textbf{simulation simulation-class t}
\\
\textbf{Slots:} \\
\textit{init-interface-args}, \textbf{accessor}: \textit{init-interface-args} - initial arguments for interface initialization. These define how will the window look \\ 
\textit{iteration-count}, \textbf{accessor}: \textit{iteration-count} - counter for the number of iterations \\ 
\textit{interface}, \textbf{accessor}: \textit{interface} - slot containing \texttt{simulation-interface}\pref{simulationinterface} instance \\ 
\textit{render-panel}, \textbf{accessor}: \textit{render-panel} - output-pane instance which is used to render graphics \\ 
\\
The subclass of the \texttt{simulation}\pref{simulation} class which controls the graphical side of the simulation.
\\ \\ \\

\label{defgsimulation}
\textit{Macro} \textbf{DEFGSIMULATION} \\
\textbf{Syntax:} \\
\textbf{defgsimulation} \textit{name (\{slot-specifier\}*) environment-class (\{agent\}*)  (\{interface-args*\})} \\
$ \Rightarrow $ \textit{new-class} 
\begin{verbatim}
slot-specifier::= slot-name | (slot-name [[slot-option]])
slot-name::= symbol
slot-option::= {:reader reader-function-name}* | 
               {:writer writer-function-name}* | 
               {:accessor reader-function-name}* | 
               {:initform form} | 
               {:type type-specifier} | 
               {:documentation string} 
function-name::= {symbol | (setf symbol)}
\end{verbatim}
\textbf{Arguments and Values:} \\
\textit{name} a non-nil symbol \\
\textit{slot-name} a symbol that is syntactically valid for use as a variable name \\
\textit{reader-function-name} a non-nil symbol \\
\textit{writer-function-name} a generic function name \\
\textit{form} form \\
\textit{type-specifier} a type specifier \\ 
\textit{environment-class} a type specifier \\ 
\textit{agent} a type specifier \\ 
\textit{interface-args} plist of initializers. If not specified, \texttt{(:visible-min-width 800 :visible-min-height 600 :title "cl-ass simulation")} is used. \\ \\
Macro \textbf{defgsimulation} defines a new graphics simulation and returns it as a new class. Every simulation defined by defgsimulation will have \texttt{graphics-simulation}\pref{graphicssimulation} as its superclass. It will also initialize the simulation and show the window with it.
\begin{snippet}
(defgsimulation cat-and-mouse 
  ((iteration-count :initform 0 :accessor it-count))
  house
  (mouse mouse mouse cat cat)
  ())
\end{snippet}


\label{makeinterface}
\textit{Generic Function} \textbf{MAKE-INTERFACE} \\
\textbf{Syntax:} \\
\textbf{make-interface} \textit{graphics-simulation} \\
$ \Rightarrow $ \textit{output-pane} \\ \\
\textbf{Method signatures:} \\
\textbf{make-interface} \textit{(gs graphics-simulation)} \\
\textbf{Arguments and Values:} \\
\textit{graphics-simulation} a graphics simulation instance \\ \\
This method creates the content of the simulation interface.


\label{clearpane}
\textit{Generic Function} \textbf{CLEAR-PANE} \\
\textbf{Syntax:} \\
\textbf{clear-pane} \textit{graphics-simulation output-pane} \\
$ \Rightarrow $ \textit{undefined} \\ \\
\textbf{Method signatures:} \\
\textbf{clear-pane} \textit{(gs graphics-simulation) output-pane} \\
\textbf{Arguments and Values:} \\
\textit{graphics-simulation} a graphics simulation instance \\ 
\textit{output-pane} rendering pane \\ \\
This method is called before the rendering method to clear the content of the \texttt{output-pane}.


\label{renderpane}
\textit{Generic Function} \textbf{RENDER-PANE} \\
\textbf{Syntax:} \\
\textbf{render-pane} \textit{graphics-simulation output-pane} \\
$ \Rightarrow $ \textit{undefined} \\ \\
\textbf{Method signatures:} \\
\textbf{render-pane} \textit{(gs graphics-simulation) output-pane} \\
\textbf{Arguments and Values:} \\
\textit{graphics-simulation} a graphics simulation instance \\ 
\textit{output-pane} rendering pane \\ \\
This method is called when the simulation should render its content into the \texttt{output-pane}.

